The Parameter Description Format

The parameter description data structure is a QTAtomContainer that, when filled out by the ImageCodecGetParameterList call, contains a set of QTAtoms for each parameter of the effect. These atoms define the base type of the parameter, the legal range of values that can be stored in it, and hints for displaying a user interface that allows users to choose values for the parameter.

The atoms in a parameter description are described in the following sections. The order in which the atoms are stored in the QTAtomContainer is important. Your application should try to present parameters to the user in the same order that they are contained in the parameter description.

Each of the atoms in a parameter description has a name; you will find constants for these in ImageCodec.h . You should use these constants when retrieving atoms from the data structure. The data stored in the atoms of the parameter description is structured, and the struct definitions are given in the atom descriptions below.

Many of the atoms must be present to create a valid parameter description. Some, though are optional, as noted.

Parameter Atom Type and ID

This atom contains information about the type and ID of the parameter. The data is contained in the following structure:



 
typedef struct

{

    QTAtomType  atomType;

    QTAtomID    atomID;

    long        atomFlags;

    Str255      atomName;

} ParameterAtomTypeAndID;

atomType: This field contains either a unique identifier for the parameter or the value kNoAtom . The unique identifier is a four character OSType that you use to retrieve the parameter's value. If this field contains kNoAtom , the "parameter" being described is actually a group description; groups are described in "Special Description Types" .
atomID: This field contains the ID of this parameter.
atomFlags: This field can contain one of the predefined values: kAtomNoFlags , kAtomNotInterpolated , or kAtomInterpolateIsOptional .; If it contains kAtomNotInterpolated , the user interface for allowing the user to specify parameter values only allows users to enter a single value for this parameter, and this value remains constant while the effect is playing.; If it contains kAtomNoFlags , the user interface allows users to enter a set of values for the parameter. This set of values are stored in a tween atom, and the value of the parameter is interpolated between these values during effect playback.; If it contains kAtomInterpolateIsOptional , the user interface defaults to allowing a single value for the parameter. If the user interface supports an "advanced" mode of operation, then a tween value can be entered for this parameter when the user interface is in this mode. An example of an advanced mode is the standard parameters dialog box: if you hold down the option key while selecting an effect, any parameters that have the kAtomInterpolateIsOptional flag set will allow a tween value to be entered.
atomName: The name of this parameter. This string value is used as the name of the control displayed in the standard parameter dialog box to enter a value for this parameter. This atom is required.

The Parameter Description Format

Parameter Atom Type and ID

Parameter Data Type

Parameter Alternate Data Type

Parameter Data Range

Parameter Data Behavior

Parameter Data Usage

Parameter Data Default Item

Special Description Types